0.0. CHARLES

Charles converts a plain text document marked-up as a fiction manuscript into a formatted manuscript in Portable Document Format.

An example manuscript lies at the end of this page.

0.1. BENEFITS

When you use Charles, you offload as much work as possible onto the software.  You write the content of your documents, and in most cases, Charles infers the types of your document's paragraphs and formats them appropriately.

When you keep your documents in plain text format, they are future-proof.  UTF-8 is a non-proprietary, universal standard for representing text.  People will be able to read your documents a hundred years from now.

To have full control over structure, content, and privacy, Charles does not use Apple's code to generate PDFs.  Charles's custom PDF generator inserts no metadata into PDFs other than the CreationDate and the Producer entries in the info dictionary.  The CreationDate is expressed in UTC.  The Producer entry is, "Charles The Manuscript Formatter".

0.2. CHARACTER SET

Charles uses an Open Source Courier-style font for PDFs. As a consequence, the formatter supports the character ranges that the fonts support.  These ranges support European languages that use alphabets derived from the Latin alphabet.


1.0. PRIVACY POLICY

1.1. DATA COLLECTION AND RETENTION

Charles does not collect user data.

1.2. USER TRACKING

Charles does not track its users.

1.3. ICLOUD ACCESS

Charles reads from, and writes to, your iCloud files. To revoke access to your iCloud data, sign out of iCloud.


2.0. MARKUP

In the bodies of manuscripts, Charles recognizes 5 types of paragraphs.  Separate paragraphs from each other with blank lines.

To force a line break, insert a bar | character where you want the break to occur.

To indicate an elision at the front of a word, use a backtick ` instead of an apostrophe.

Users with English keyboards can insert UTF-8 sequences for accented characters with the following escape sequences:

\' (apostrophe) followed by a vowel inserts the vowel with an acute accent.

\` (backtick) followed by a vowel inserts the vowel with a grave accent.

\^ followed by a vowel inserts the vowel with a circumflex.

\, followed by an uppercase C or a lowercase c inserts the character with a cedilla.

\~ followed by an uppercase N or a lowercase n inserts the character with a tilde.

\: followed by a vowel or an uppercase Y or a lowercase y inserts the character with a dieresis.

\u followed by a decimal number inserts the Unicode character with the specified code point.  If the code point is followed by digits that are part of the document text, those digits must be repesented by their own \u code points, or the digits will be interpreted as part of the code point.

2.1. PARTS

Parts are paragraphs that begin with an asterisk:

*PART $P

Parts are centered and emboldened on a page by themselves. Any occurrence of $P in a part is replaced with the number of the part. Parts are numbered from 1.

2.2. SECTIONS

Sections are paragraphs that begin with an equals sign:

=Section $S

Sections are centered and emboldened on a page by themselves. Any occurrence of $S in a section is replaced with the number of the section. Sections are numbered from 1.

2.3. CHAPTERS

Chapters are paragraphs that begin with a dot:

.Chapter $C

Chapters are centered and emboldened. Any occurrence of $C in a chapter is replaced with the number of the chapter. Chapters are numbered from 1.

2.4. NOTES

Note paragraphs contain editorial content that is removed by the formatter.  To be recognized, note paragraphs must begin with [[ and end with ]]. A note "paragraph" can contain multiple paragraphs of text.

[[This is a note paragraph.]]

To insert editorial content that is not removed by the formatter, insert the content inside single bracket pairs: [Note].

2.5. BREAK PARAGRAPHS

A break paragraph indicates a break in the narrative. To insert a break paragraph, place # by itself in a paragraph of 1 line.

This the paragraph before the break.

#

This is the paragraph after the break.

2.6. BODY PARAGRAPHS

Paragraphs that are not sections, chapters, breaks, or notes are body paragraphs.

To set a body paragraph in italics, precede paragraph text with a % character.


3.0. EMPHASIS

Charles provides no means for you to directly change the font. Boldface is too obtrusive outside of headings, and courier oblique is not oblique enough because it is a fixed-pitch font with little room for leaning. As a consequence, it is easy to fail to recognize oblique words embedded in a roman sentence. I have made the executive decision that all emphasis is accomplished with underlining.

Charles underlines words that are bookended with underscores. Each word must be underlined separately.

_This_ _is_ _underlined_ _text._ _Underline_-_each_-_word_-_in_-_a_-hyphenate._

You may get away with underlining _a single-line passage of text_, but if your underlined passage is subsequently split across lines by the formatter, the underlining will be removed.


4.0. TITLE PAGES

A title page with placeholder information is automatically added to your manuscripts. Charles does not format title pages by themselves. You must have at least one paragraph of manuscript for Charles to produce PDF output.

To replace title page placeholder text, add the following lines to the beginning of your manuscripts. Replace the values after the colons with your information.

Title: THE MAGNIFICENT GUPPY
Author:
  By
  \u32
  Carnaby Fimblethicke
Revision: February 2018
Contact: fimblethwicke@nowhere.net
Header:
  Charles
  GUPPY

To create multiline values, break the keyword line after the colon. Place the lines of your multiline value after the keyword line.

Each line of a multiline value must begin with a space. To indicate a blank line, insert a line containing only a space character or the Unicode escape sequence for a space character: \u32.

Author:
  By
  \u32
  Carnaby Fimblethwicke
  \u32
  and
  \u32
  His dog, Horatio

To make today's date the Revision, make its value $D.

Revision: $D

To insert the manuscript word count, use $W.

Revision: $W

To insert the page count, use $P.

Revision: $P

You can place anything you like in the value of Revision. If you use $D, it must appear by itself on a line.

If you use $W, it must appear at the start of a line. If $W appears on the line by itself, the formatter will follow the word count with WORDS. If you want different text, follow $W with the text that you want.

If you use $P, it must appear at the start of a line. If $P appears on the line by itself, the formatter will follow the word count with PAGES. If you want different text, follow $P with the text that you want.

Revision:
  Revision 1.0
  $W
  $P
  $D

The Header keyword introduces 2 lines that specify the content of a manuscript's running header. The first line should contain the author's last name. The second line should contain 1 or 2 words from the title. Charles adds the page number to the header.

Header:
  Charles
  GUPPY

Charles supports 3 optional title page elements: Watermark, Copyright, and Language.

Watermark:
  COPYRIGHT (c) 2018,
  Carnaby Fimblethwicke.

The 3 characters (C) occurring anywhere inside the Watermark and Contact information are replaced with the copyright symbol by the formatter.

Watermark lines are added centered, rotated left to the background of every page. Watermarks are set in boldface at 90% transparency at 60 points.

Charles's watermarks cannot be removed or edited by tools that modify PDF annotations.

The Copyright and Language data are used in ebooks.

Copyright: 2025, Carnaby Fimblethwicke.
Language: en

If present, the Copyright data appears on the title page of ebooks.

If present, the Language specification must be a BCP 47 language tag. If the Language specification is not present, the language code defaults to 'en' for English.


5.0. EXAMPLE

An example manuscript fragment follows.  Copy and paste it into the editor.

Title: THE MAGNIFICENT GUPPY
Revision:
  $D
  $W
  $P
Author:
  By
  \u32
  Carnaby Fimblethwicke
Contact: fimblethwicke@nowhere.net
Header:
  Charles
  GUPPY
Watermark:
  Copyright
  (C) 2018,
  Carnaby
  Fimblethwicke.

*PART $P

=SECTION $S

.CHAPTER $C

My brother was unfit to rule. Most of these people would support him right
up until it was clear that they had made a mistake. Then they would
abandon him to save themselves. Some of the advisors must have an opinion
similar to mine that they didn't dare voice. Would they support me if I
removed my brother from the throne?  Perhaps. Would I have to kill my
brother? Most likely. Certainly all of his supporters. No. I would have to
kill my brother for sure. Mercy would be foolish. Time to make two lists
and divide up the nobility between them.

.CHAPTER $C

We rode out to the royal tombs in our mother's carriage, one brother on
each side of her. She wore her standard black outfit, and we wore our
night-blue uniforms. The carriage projected our trajectory onto a road map
on the bottom of the bulbous smoked canopy and above the map, a view of the
entrance to the Precinct of the Dead. The gate was open, but sentries
barred the way. Our estimated time of arrival ticked down over the image.
